home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kconfig.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-10-01  |  9.4 KB  |  297 lines
  1. /*
  2.    This file is part of the KDE libraries
  3.    Copyright (c) 1999 Preston Brown <pbrown@kde.org>
  4.    Copyright (C) 1997 Matthias Kalle Dalheimer <kalle@kde.org>
  5.  
  6.    This library is free software; you can redistribute it and/or
  7.    modify it under the terms of the GNU Library General Public
  8.    License as published by the Free Software Foundation; either
  9.    version 2 of the License, or (at your option) any later version.
  10.  
  11.    This library is distributed in the hope that it will be useful,
  12.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.    Library General Public License for more details.
  15.  
  16.    You should have received a copy of the GNU Library General Public License
  17.    along with this library; see the file COPYING.LIB.  If not, write to
  18.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19.    Boston, MA 02110-1301, USA.
  20. */
  21.  
  22. #ifndef _KCONFIG_H
  23. #define _KCONFIG_H
  24.  
  25. class QTimer;
  26.  
  27. #include <qvaluelist.h>
  28.  
  29. #include "kconfigbase.h"
  30. #include "klockfile.h"
  31.  
  32. class KConfigPrivate;
  33.  
  34. /**
  35. * Access KDE Configuration entries.
  36. *
  37. * This class implements KDE's default configuration system.
  38. *
  39. * @author Kalle Dalheimer <kalle@kde.org>, Preston Brown <pbrown@kde.org>
  40. * @see KGlobal::config(), KConfigBase, KSimpleConfig
  41. * @short KDE Configuration Management class
  42. */
  43. class KDECORE_EXPORT KConfig : public KConfigBase
  44. {
  45.   Q_OBJECT
  46.  
  47. public:
  48.  
  49.   /**
  50.    * Constructs a KConfig object.
  51.    *
  52.    * @param fileName A file to parse in addition to the
  53.    *        system-wide file(s).  If it is not provided, only global
  54.    *        KDE configuration data will be read (depending on the value of
  55.    *        @p bUseKDEGlobals).
  56.    * @param bReadOnly Set the config object's read-only status. Note that the
  57.    *        object will automatically become read-only if either the user does not have
  58.    *        write permission to @p fileName or if no file was specified.
  59.    * @param bUseKDEGlobals Toggle reading the global KDE configuration file.
  60.    * @param resType the place to look in (config, data, etc) See KStandardDirs.
  61.    */
  62.   KConfig( const QString& fileName = QString::null,
  63.           bool bReadOnly = false, bool bUseKDEGlobals = true, const char *resType="config");
  64.  
  65.   KConfig(KConfigBackEnd *backEnd, bool bReadOnly = false);
  66.  
  67.   /**
  68.    * Destructs the KConfig object.
  69.    *
  70.    * Writes back any dirty configuration entries, and destroys
  71.    * dynamically created objects.
  72.    */
  73.   virtual ~KConfig();
  74.  
  75.   /**
  76.    * Clears all entries out of the @p dirtyEntryMap, so the
  77.    * values will not be written to disk on a later call to
  78.    * sync().
  79.    *
  80.    * @param bDeep If true, the dirty map is actually emptied.
  81.    *        otherwise, the config object's global dirty flag is set to
  82.    *        false, but the dirty entries remain in the dirty entry
  83.    *        map.
  84.    *
  85.    * @see KConfigBase::rollback
  86.    */
  87.   virtual void rollback(bool bDeep = true);
  88.  
  89.  
  90.   /**
  91.    * Returns a list of groups that are known.
  92.    * @return a list of of groups
  93.    */
  94.   virtual QStringList groupList() const;
  95.  
  96.   /**
  97.    * Returns a map (tree) of entries for all entries in a particular
  98.    * group.
  99.    *
  100.    *  Only the actual entry string is returned, none of the
  101.    * other internal data should be included.
  102.    *
  103.    * @param pGroup A group to get keys from.
  104.    * @return A map of entries in the group specified, indexed by key.
  105.    *         The returned map may be empty if the group is not found.
  106.    */
  107.   virtual QMap<QString, QString> entryMap(const QString &pGroup) const;
  108.  
  109.   /**
  110.    * Clears all internal data structures and then reread
  111.    * configuration information from disk.
  112.    */
  113.   virtual void reparseConfiguration();
  114.  
  115.   /**
  116.    * Set the file mode for newly created files.
  117.    *
  118.    * @param mode the mode for new files as described in chmod(2)
  119.    * @see man:chmod(2) for a description of @p mode
  120.    */
  121.   void setFileWriteMode(int mode);
  122.  
  123.   /**
  124.    * Forces all following write-operations being performed on kdeglobals,
  125.    * independent of the bGlobal flag in writeEntry().
  126.    * @param force true to force writing in kdeglobals
  127.    * @see forceGlobal
  128.    */
  129.   void setForceGlobal( bool force ) { bForceGlobal = force; }
  130.  
  131.   /**
  132.    * Returns true if all entries are being written into kdeglobals.
  133.    * @return true if all entries are being written into kdeglobals
  134.    * @see setForceGlobal
  135.    */
  136.   bool forceGlobal() const { return bForceGlobal; }
  137.  
  138.   /**
  139.    * Checks whether the config file contains the update @p id
  140.    * as contained in @p updateFile. If not, it runs kconf_update
  141.    * to update the config file.
  142.    *
  143.    * If you install config update files with critical fixes
  144.    * you may wish to use this method to verify that a critical
  145.    * update has indeed been performed to catch the case where
  146.    * a user restores an old config file from backup that has
  147.    * not been updated yet.
  148.    * @param id the update to check
  149.    * @param updateFile the file containing the update
  150.    * @since 3.1
  151.    */
  152.   void checkUpdate(const QString &id, const QString &updateFile);
  153.  
  154.   /**
  155.    * Copies all entries from this config object to a new config
  156.    * object that will save itself to @p file.
  157.    *
  158.    * Actual saving to @p file happens when the returned object is
  159.    * destructed or when sync() is called upon it.
  160.    *
  161.    * @param file the new config object will save itself to.
  162.    * @param config optional config object to reuse
  163.    * @since 3.2
  164.    */
  165.   KConfig* copyTo(const QString &file, KConfig *config=0) const;
  166.  
  167.   /**
  168.    * Returns a lock file object for the configuration file or 0 if
  169.    * the backend does not support locking.
  170.    * @param bGlobal if true, return the lock file for the global config file
  171.    *
  172.    * NOTE: KConfig::sync() requires a lock on both the normal and global
  173.    * config file. When calling KConfig::sync() while having a lock on the
  174.    * global config file, the normal config file MUST be locked AS WELL and the 
  175.    * normal config file MUST be locked BEFORE the global config file!
  176.    * Otherwise there is a risk of deadlock.
  177.    * @since 3.3
  178.    */
  179.   KLockFile::Ptr lockFile( bool bGlobal=false );
  180.  
  181. protected:
  182.  
  183.   /**
  184.    * Returns true if the specified group is known.
  185.    *
  186.    * @param group The group to search for.
  187.    * @returns true if the group exists.
  188.    */
  189.   virtual bool internalHasGroup(const QCString &group) const;
  190.  
  191.   /**
  192.    * @internal
  193.    * Returns a map (tree) of the entries in the specified group.
  194.    *
  195.    * Do not use this function, the implementation / return type are
  196.    * subject to change.
  197.    *
  198.    * @param pGroup the group to provide a KEntryMap for.
  199.    * @return The map of the entries in the group.
  200.    */
  201.   virtual KEntryMap internalEntryMap(const QString &pGroup) const;
  202.  
  203.   /**
  204.    * @internal
  205.    * Returns a copy of the internal map used to hold all entries.
  206.    *
  207.    * Do not use this function, the implementation / return type are
  208.    * subject to change.
  209.    *
  210.    * @return The map of the entries in the group.
  211.    */
  212.    virtual KEntryMap internalEntryMap() const { return aEntryMap; }
  213.  
  214.   /**
  215.    * Inserts a (key, value) pair into the internal storage mechanism of
  216.    * the configuration object.
  217.    *
  218.    * @param _key The key to insert.  It contains information both on
  219.    *        the group of the key and the key itself. If the key already
  220.    *        exists, the old value will be replaced.
  221.    * @param _data the KEntry that is to be stored.
  222.    * @param _checkGroup When false, assume that the group already exists.
  223.    */
  224.   virtual void putData(const KEntryKey &_key, const KEntry &_data, bool _checkGroup=true);
  225.  
  226.   /**
  227.    * Looks up an entry in the config object's internal structure.
  228.    *
  229.    * @param _key The key to look up  It contains information both on
  230.    *        the group of the key and the entry's key itself.
  231.    * @return the KEntry value (data) found for the key.  KEntry.aValue
  232.    * will be the null string if nothing was located.
  233.    */
  234.   virtual KEntry lookupData(const KEntryKey &_key) const;
  235.  
  236.   /**
  237.    * Contains all key,value entries, as well as some "special"
  238.    * keys which indicate the start of a group of entries.
  239.    *
  240.    * These special keys will have the .key portion of their KEntryKey
  241.    * set to QString::null.
  242.    */
  243.   KEntryMap aEntryMap;
  244.  
  245. private:
  246.   /**
  247.    * @internal
  248.    * copy-construction and assignment are not allowed
  249.    */
  250.   KConfig( const KConfig& );
  251.   /**
  252.    * @internal
  253.    * copy-construction and assignment are not allowed
  254.    */
  255.   KConfig& operator= ( const KConfig& rConfig );
  256.  
  257. private:
  258.   bool bGroupImmutable : 1; // Current group is immutable.
  259.   bool bFileImmutable  : 1; // Current file is immutable.
  260.   bool bForceGlobal    : 1; // Apply everything to kdeglobals.
  261. protected:
  262.   virtual void virtual_hook( int id, void* data );
  263. private:
  264.   KConfigPrivate *d;
  265. };
  266.  
  267. /**
  268.  * KConfig variant using shared memory
  269.  *
  270.  * KSharedConfig provides a reference counted, shared memory variant
  271.  * of KConfig.
  272.  */
  273. class KDECORE_EXPORT KSharedConfig : public KConfig, public KShared
  274. {
  275.   friend class QValueList<KSharedConfig*>;
  276. public:
  277.   typedef KSharedPtr<KSharedConfig> Ptr;
  278.  
  279. public:  
  280.   /**
  281.    * Returns a ref-counted pointer to a shared read-write config object.
  282.    * @param fileName the name of the file to use for the configuration
  283.    * @param readOnly set the config object's read-only status
  284.    * @param bUseKDEGlobals Toggle reading the global KDE configuration file.
  285.    */
  286.   static KSharedConfig::Ptr openConfig(const QString& fileName, bool readOnly = false,
  287.     bool bUseKDEGlobals = true);
  288.  
  289. private:
  290.   KSharedConfig( const QString& fileName, bool readOnly, bool useKDEGlobals );
  291.   ~KSharedConfig();
  292.  
  293.   static QValueList<KSharedConfig*> *s_list;
  294. };
  295.  
  296. #endif
  297.